Skip to content

Default to OAS-compliant handling of additionalProperties#21170

Open
ctreatma wants to merge 7 commits intoOpenAPITools:masterfrom
ctreatma:default-oas-compliant
Open

Default to OAS-compliant handling of additionalProperties#21170
ctreatma wants to merge 7 commits intoOpenAPITools:masterfrom
ctreatma:default-oas-compliant

Conversation

@ctreatma
Copy link
Copy Markdown
Contributor

@ctreatma ctreatma commented Apr 28, 2025

This changes the default value for disallowAdditionalPropertiesIfNotPresent from true to false, which means that the generator will now, by default, produce code that complies OpenAPI standards with respect to the handling of additionalProperties.

Note that a number of example configs did not have to be updated as a result of this change, which indicates that the disallowAdditionalPropertiesIfNotPresent option had no effect on the generators used in those examples.

Some of the Python templates had references to {{#disallowAdditionalPropertiesIfNotPresent}}. It turns out that this check behaves differently if users leave disallowAdditionalPropertiesIfNotPresent unspecified than it does if users explicitly configure disallowAdditionalPropertiesIfNotPresent: true. That means that swapping the default would be a breaking change for Python generators. To work around that, I've introduced a new legacyDisallowAdditionalPropertiesDefaultBehavior flag that is used by the impacted Python generators. Users who were using the impacted generators and were not explicitly configuring disallowAdditionalPropertiesIfNotPresent can continue to generate equivalent code by setting these options:

disallowAdditionalPropertiesIfNotPresent: true
legacyDisallowAdditionalPropertiesDefaultBehavior: true

Closes #21169
Closes #21121, closes #21446 (by making expected behavior documented in those issues the default rather than requiring explicit config)
Closes #16575 (duplicate)

PR checklist

  • Read the contribution guidelines.
  • Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
  • Run the following to build the project and update samples:
    ./mvnw clean package || exit
    ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
    ./bin/utils/export_docs_generators.sh || exit
    
    (For Windows users, please run the script in Git BASH)
    Commit all changed files.
    This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
    These must match the expectations made by your contribution.
    You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
    IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
  • File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@ctreatma ctreatma force-pushed the default-oas-compliant branch from 7c220fc to b38c2fb Compare May 1, 2025 20:43
@ctreatma
Copy link
Copy Markdown
Contributor Author

ctreatma commented May 1, 2025

@wing328 When you have a moment, please take a look. To provide a more complete fallback for this change, I added a new config flag for Python generators to maintain pre-existing behavior around the disallowAdditionalPropertiesIfNotPresent option. Let me know if you'd like to see this handled differently.

Comment thread bin/configs/python-fastapi.yaml
Comment thread samples/server/petstore/python-fastapi/src/openapi_server/models/order.py Outdated
@ctreatma ctreatma force-pushed the default-oas-compliant branch 3 times, most recently from 9b01374 to 69520f0 Compare May 1, 2025 22:21
@ctreatma ctreatma force-pushed the default-oas-compliant branch 2 times, most recently from 9ef6192 to 2d4fb51 Compare May 2, 2025 16:14
@ctreatma ctreatma force-pushed the default-oas-compliant branch 7 times, most recently from 6e1a59c to 6760d99 Compare June 16, 2025 19:19
@ctreatma ctreatma force-pushed the default-oas-compliant branch from 6760d99 to f9aa3a6 Compare August 1, 2025 16:40
@ctreatma ctreatma force-pushed the default-oas-compliant branch from f9aa3a6 to 6ecb775 Compare September 2, 2025 15:00
@ctreatma ctreatma force-pushed the default-oas-compliant branch 2 times, most recently from f87100e to 745c360 Compare October 9, 2025 18:46
@ctreatma ctreatma force-pushed the default-oas-compliant branch from 745c360 to d061943 Compare November 19, 2025 18:27
@ctreatma
Copy link
Copy Markdown
Contributor Author

@wing328 please let me know if there's anything I can do to help shepherd this proposal through review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant